Tinn-R FAQ
Frequently Asked Questions on Tinn-R
Version 1.7 02/04/2005 by Ph. Grosjean

________________________________________________________________________________
Table of Contents
________________________________________________________________________________

1. Introduction
  1.1 Obtaining this document
  1.2 Feedback, suggestions & bug report
2. Tinn-R Installation
  2.1 What is Tinn-R?
  2.2 Where can I get the latest version of Tinn-R?
  2.3 How do I install Tinn-R?
  2.4 Where should I start?
  2.5 Can I get the source code?
3. Configuration
  3.1 How can I add a shortcut to Tinn-R in the start menu or in the desktop?
  3.2 Can I save or reuse my preferences on another computer?
  3.3 How to open a file in Tinn-R by double-click in the explorer?
  3.4 How to define the Rgui to start from within Tinn-R?
  3.5 Can I define Tinn-R as the default editor for R objects?
  3.6 Can I use Emacs or WinEdt syntax highlighting color instead?
  3.7 What is "Call-tip with R as server" in the application options?
  3.8 Can I start R and Tinn-R at once?
4. Keyboard shortcuts
  4.1 How do I define shortcuts for the R tools in Tinn-R?
  4.2 Can I define bookmarks to ease navigation in my documents?
  4.3 Is there a shortcut for cycling through opened files?
  4.4 Is it a shortcut for '<-' and '->' in S language?
  4.5 I am editing a table. Can I select text in column-mode in it?
5. Miscellaneous
  5.1 What is the left gutter for?
  5.2 Can I run my code step-by-step?
  5.3 Is it a graphical debugger for my R functions?
  5.4 What is the Tools panel?
  5.5 Can I copy and paste syntax highlighted R code in Word/Web/LaTeX?

________________________________________________________________________________
1. Introduction
________________________________________________________________________________

Most frequently asked questions about Tinn-R.

1.1 Obtaining this document
---------------------------
The latest version of this document is always available from
'http://www.sciviews.org/Tinn-R/Tinn-R_FAQ.txt'

1.2 Feedback, suggestions & bug report
--------------------------------------
Feedback via email to both <phgrosjean@sciviews.org> and
<joseclaudio.faria@terra.com.br> is most welcome. If you submit a bug report,
please, be as accurate as possible. Indicate the Tinn-R version (Help -> About),
your system (ex: Windows 98SE, or Windows XP pro SP2) and language (English,
French, Portugese, ...). If the bug is related to a communication with Rgui,
indicate also which version of R do you use, and whether you run Rgui in MDI, or
SDI mode, or SciViews R Console.

________________________________________________________________________________
2. Tinn-R Installation
________________________________________________________________________________

2.1 What is Tinn-R?
-------------------
Tinn is a small ASCII file editor primarily intended as a better replacement
of the default Notepad.exe under Windows. Tinn is the recursive acronym
'Tinn is not Notepad'. Tinn-R is an extension of Tinn that provides additional
tools to control R (Rgui in MDI or SDI mode, see http://cran.r-project.org, or
SciViews R console, see http://www.sciviews.org/SciViews-R). As such, Tinn-R
is a feature-rich replacement of the basic script editor provided with Rgui.
It provides syntax-highlighting, submission of code in whole, or line-by-line,
and many other useful tools to ease writting and debugging of R code. Both Tinn
and Tinn-R are distributed under the GPL 2 or above license. A copy of this
license can be obtained at: http://www.gnu.org/copyleft/gpl.html.

2.2 Where can I get the latest version of Tinn-R?
-------------------------------------------------
The latest version of Tinn-R can be downloaded from its web site:
http://www.sciviews.org/Tinn-R. Currently, this is the only way Tinn-R is
distributed, but you are allowed to redistribute it freely. If you do so,
please, make sure you distribute always the latest version.

2.3 How do I install Tinn-R?
----------------------------
You have the choice between a setup file that does everything for you, or a
zipped version that you can manually unzip somewhere. In fact, the whole
program is contained in 'Tinn-R.exe' and it can be run from where you place
it on your hard disk drive without further installation. Once you downloaded
Tinn-R x.x.x.x beta/stable.zip from the web site, just unzip it where you want
and run Tinn-R.exe from there. You can use a software like Winzip to unzip it
(see http://www.winzip.com). Tinn-R runs on Windows 9X/Me/Millenium/NT/2000/XP.
You do not need administrative rights to install or run it, providing you have
enough rights on the directory where you want to install it (if you have
problems, contact you computer or network administrator). Note that if you
install Tinn-R, you probably want to use it with R. R must be installed
separately and can be obtained from http://cran.r-project.org.

Alternatively, Tinn-R is part of, and is installed with SciViews-R series of
companion applications for R (http://www.sciviews.org/SciViews-R). The setup
of SciViews-R also creates a shortcut for Tinn-R in the start menu and 
associates *.r, *.R, *.q and *.Q files with Tinn-R automatically, thus,
simplifying the integration of Tinn-R on your computer, the same way the
dedicated Tinn-R setup operates.

2.4 Where should I start?
-------------------------
The files 'Tinn-R_Read me.html', 'Tinn-R_Leia me.html' (the same document in
Portuguese) and 'Tinn-R_Lisez moi.html' (in French) in the \doc subdirectory of
Tinn-R are rapid introductions to the particular features Tinn-R provides. You
should take a couple of seconds to read them before you start working in Tinn-R.

2.5 Can I get the source code?
------------------------------
Yes. You can get and modify the source code of Tinn-R (and redistribute your
changes if you respect the terms of the GPL license). To get the source code,
send an email to Jos Cludio Faria <joseclaudio.faria@terra.com.br>.

________________________________________________________________________________
3. Configuration
________________________________________________________________________________

3.1 How can I add a shortcut to Tinn-R in the start menu or in the desktop?
---------------------------------------------------------------------------
This is done by the installer. If you want to do it manually, follow these
steps. In the object explorer, right-click on the file 'Tinn-R.exe' and select
'Create shortcut'. Drag & drop this shortcut to the desktop, or where you want
to place it in the start menu.

3.2 Can I save or reuse my preferences on another computer?
-----------------------------------------------------------
You have a save/restore configuration tool in 'Options/Backup/Restore system
options'. Just use it (backup your config on one computer, copy it to another
one and use restore there)!

3.3 How to open a file in Tinn-R by double-click in the explorer?
-----------------------------------------------------------------
You need to register Tinn-R as the default program to open files with a given
extension. Either you check this option during installation, or follow the next
procedure to do it manually. To open *.R files (R scripts) with Tinn-R, locate
one such file in your disk with the files explorer. Right-click on this file,
and select 'Open with -> Choose program...' in the context menu. Then click
'Browse' in the 'Open with' dialog box and select 'Tinn-R.exe'. Make sure the
option 'Always use the selected program to open this kind of file' is selected.
Click 'OK'. Now, when you double-click on a *.R file in the Windows explorer, it
will be opened in Tinn-R.

3.4 How to define the Rgui to start from within Tinn-R?
-------------------------------------------------------
You can start you preferred Rgui directly from Tinn-R. To define it, go to
'Options/Main/Application'. At the bottom of this dialog box, you can
determine the path of the Rgui executable to start from within Tinn-R. Select
'Rgui.exe' (for instance, from 'C:\Program Files\R\rw2010\bin\Rgui.exe'), or
'RConsole.exe' (for instance, from 'C:\Program Files\SciViews\bin\RConsole.exe')
to use respectively the standard Rgui, or SciViews R Console. Note: to use R
with Tinn-R, you must first install it from http://cran.r-project.org. To use
SciViews R Console, install it from http://www.sciviews.org/SciViews-R. With
Rgui, you still have the choice between the MDI or SDI mode. To switch from one
to the other, in Rgui, select 'Edit -> GUI preferences', switch (MDI/SDI) and
click on 'Save', then 'OK' without changing the name of file proposed. Then,
click 'OK' or 'Cancel' in the 'Rgui Configuration Editor' (ignore the possible
message), and restart Rgui (changes are not taken into account in the current
session). Try to use Rgui in both MDI and SDI mode with Tinn-R before to decide
which configuration you prefer.

3.5 Can I define Tinn-R as the default editor for R objects?
------------------------------------------------------------
No, currently, it does not work that way. Use the internal script editor of
Rgui to edit() or fix() R objects.

3.6 Can I use Emacs or WinEdt syntax highlighting color instead?
----------------------------------------------------------------
Just set your preferred color scheme in 'Options/Syntax/Color preferences'.
You just need to set it once. To change color scheme on other computers, just
use the 'Options/Backup/Restore system options' configuration functions
(see FAQ 3.2).

3.7 What is "Call-tip with R as server" in the application options?
-------------------------------------------------------------------
Call-tips are tooltips displaying the syntax of the currently used R function.
By default, if you enter the name of a function followed by an open bracket,
like 'sd(' in a R code document, then Tinn-R understands that you call the 'sd'
R function and refreshes your memory about its syntax by showing the following
call-tip: 'x, na.rm=FALSE', that is, 'sd' accepts two arguments: 'x', and
'na.rm' with the later having as default value 'FALSE'. Tinn-R uses a database
with the syntax of most common functions in R. However, neither functions in
additional packages, nor your custom ones are cached in this database, and it is
tedious to add them all manually. Tinn-R offers a second mechanism too: direct
interrogation of R. This is done through DDE, using functions automatically
loaded when you start the svIDE R package from the SciViews bundle that you can
found on CRAN. To use this extra functionnality, you need: (1) to download and
install the SciViews bundle (if your computer is connected to the Internet, use
Rgui menu Packages/Install Package(s) from CRAN... and select 'SciViews' in
the list), (2) to load svIDE package in the current R session using:

> library(svIDE)

and (3) to enable this function in 'Options/Main/Application/Call-tip with R as
server'. On some computer, the delay for synchronisation should be adjusted too
(if Tinn-R seems to freeze while querying R for call-tips and you got not
result, increase the value a little bit).

Note that this functionnality is still somehow experimental. Once the mechanism
will be completelly developed, other functions will be provided to Tinn-R, like
completion lists or advanced debugging features, for instance.

3.8 Can I start R and Tinn-R at once?
-------------------------------------
There are certainly many ways to do so. Here is a way to start Tinn-R
automatically from R and to configure R as a call-tip server in a single step.
First, indicate to R that you want to use Tinn-R as your IDE (Integrated
Development Environment). You do so, starting a fresh R session and using:

> options(IDE = "c:/program files/Tinn-R/bin/Tinn-R.exe")

Of course, you have to indicate the actual location of Tinn-R.exe on your
computer! When this is done, Tinn-R is started automatically when you load
svIDE, at the same time as the R call-tip server is installed (see FAQ 3.7):

> library(svIDE)

If this works fine when you do it manually, and you want these steps to be
issued *every time* you start R, edit the 'Rprofile' file (located in the \etc\
subdirectory of R, thus something like c:\Program Files\R\rw2010\etc\Rprofile).
Add those three lines of code at the end of that Rprofile file, and Tinn-R will
start everytime you open a R session:

# Start Tinn-R automatically and configure the R call-tip server
options(IDE = "c:/program files/Tinn-R/bin/Tinn-R.exe")
library(svIDE)

To make sure everything works fine, close both R and Tinn-R. Restart R. Tinn-R
should start at the same time. Now, create a very simple function in R,
for instance:

> cube <- function(x) x^3

Switch to Tinn-R and type: 'cube('. You should get a call-tip displaying 'x' if
the R call-tip server was correctly installed.

________________________________________________________________________________
4. Keyboard shortcuts
________________________________________________________________________________

4.1 How do I define shortcuts for the R tools in Tinn-R?
--------------------------------------------------------
Go to 'R/Hotkeys of R'. Then, define your favorite shortcuts for the various
R tools and make sure to activate them (Option -> Active).

4.2 Can I define bookmarks to ease navigation in my documents?
--------------------------------------------------------------
Yes, you can define up to 10 bookmarks in each of your opened documents. To
define the bookmark, use Ctrl+Shift+[0-9] (a key from 0 to 9), and to go to the
corresponding bookmark, use Ctrl+[0-9]. A visual indicator appears in the right
margin at the location of your bookmarks to remind you where they are.

4.3 Is there a shortcut for cycling through opened files?
---------------------------------------------------------
Yes, you can use 'Ctrl+Tab' to go to next file, and 'Ctrl+Shift+Tab' to go to
previous one when several files are loaded simultaneously in Tinn-R.

4.4 Is it a shortcut for '<-' and '->' in S language?
-----------------------------------------------------
The (non user configurable) shortcut for '->' is 'Ctrl+Add' key
(numeric keypad). Similarly, 'Ctrl+Substract' (numeric keypad) is a shortcut for
'<-' ('->' and '<-' are assigment symbols in the S language).

4.5 I am editing a table. Can I select text in column-mode in it?
-----------------------------------------------------------------
Yes you can, but you must first make sure that this option is selected. Go to
'Options/Main/Editor/Options' tab and check (x) 'Alt sets column modes'.
Once it is done, if you press 'Alt' key while you select your text with the
mouse in Tinn-R, you can select a continuous block of text, for instance, one
or several contiguous columns in an ASCII table (column-mode selection).

________________________________________________________________________________
5. Miscellaneous
________________________________________________________________________________

5.1 What is the left gutter for?
--------------------------------
In Tinn-R, bookmarks are visually displayed in the left gutter (use 'Ctrl+Shift
+[0-9]' to set bookmarks and 'Ctrl+[0-9]' to navigate to them). It also displays
the line numbers. You must set gutter 'Visible' in 'Options/Main/Editor/Display
tab' (and also 'Show line number') to activate this feature.

5.2 Can I run my code step-by-step?
-----------------------------------
Yes, but for most convenient use of this function, you must place Tinn-R and R
side by side on your screen and click on the 'Send line' icon with the mouse
(fourth button on the R toolbar). If you use a shortcut, you can submit just one
line, because the R console gets the focus when code is send to R.
Alternatively, you can set Tinn-R as a 'topmost' window on top of R using
'Options/On top', but then, Tinn-R permanently hides the R console and there is
chance that you don't see a part of the output generated in R during your
step-by-step code execution.

5.3 Is it a graphical debugger for my R functions?
--------------------------------------------------
Not in Tinn-R yet, but you can download the excellent 'debug' package on CRAN.
Take a look at the 'mtrace' function there.

5.4 What is the Tools panel?
----------------------------
It is a panel you can open at the left or at the right of your text. It helps
you manage large projects with multiple documents. The 'Computer' tab allows you
to explore your computer disks and open one or several files without using 'File
/Open', or switching to the Windows file explorer. The 'Project' tab is a
convenient manager for all files collected in a given project.

5.5 Can I copy and paste syntax highlighted R code in Word/Web/LaTeX?
---------------------------------------------------------------------
Syntax highlighted code enhances visibility of code. It is convenient in the
code editor, but could be useful too for pieces of code presented elsewhere (in
a report, in a web page, in a LaTeX document. Tinn-R allows you to copy code,
keeping syntax highlighting color with 'Edit/Copy formatted/RTF/HTML/TeX'.

   More to some soon ...
